home *** CD-ROM | disk | FTP | other *** search
/ CD Concept 6 / CD Concept 06.iso / mac / UTILITAIRE / RLaB / help / getline < prev    next >
Encoding:
Text File  |  1995-01-23  |  2.7 KB  |  89 lines  |  [TEXT/RLAB]
  1. getline:
  2.  
  3. Syntax:    getline ( FN )
  4.     getline ( FN, LL )
  5.  
  6. Description:
  7.  
  8.     Getline returns an N-element list which contains all of the
  9.     tokens from a line in the file described by FN. The tokens are
  10.     delimited by whitespace. Numbers are installed in the list as
  11.     numeric scalars, everything else is installed as scalar
  12.     strings.
  13.  
  14.     The list elements have numeric indices, and are numbered from
  15.     1 to N. The 1st element containing the 1st token on the line,
  16.     and the Nth element containing the last token on the line. The
  17.     newline is not returned as a token.
  18.  
  19.     Getline will also recognize everything enclosed within a pair
  20.     of `"' as a string, including escape characters.
  21.  
  22.     Getline will always return a list-object. When an empty-line
  23.     has been read, getline returns an empty list. Getline will
  24.     terminate on an End-Of-File (EOF).
  25.  
  26.     The filename can be a string that specifies a sub-process (see
  27.     `help FILES'), in which case getline() will run the
  28.     sub-process, and read from the process's standard output.
  29.  
  30.     The second, and optional argument, LL, forces getline to
  31.     return the entire line as a string, without any parsing. If LL
  32.     is <= 0, then getline will read lines as long as 1024
  33.     characters. If LL > 0, then getline will read lines as long as
  34.     LL characters.
  35.  
  36.     Examples:
  37.  
  38.     To get input interactively:
  39.  
  40.     > printf( "Enter a string and a number: " ); x = getline( "stdin" );
  41.     Enter a string and a number: test-string 1.234e5
  42.     > show(x)
  43.        name:   x     
  44.        class:  list  
  45.            n:  2     
  46.     > x.[1]
  47.     test-string
  48.     > x.[2]
  49.      2 =
  50.      1.23e+05
  51.  
  52.     Given a file named `test', which contains the following lines:
  53.  
  54.     jcool  259  4 1075  822 vt01     S   Dec 29  9:32 X :0 -p 1 -s 5 
  55.     jcool  256  0   21    0 console  S   Dec 29  0:00 startx 
  56.     jcool  261  0  338   88 console  S   Dec 29  0:16 twm 
  57.     jcool  288  8  635  333 ?        S   Dec 29  2:00 emacs 
  58.     jcool  287  0  408   65 console  S   Dec 29  0:01 xclock 
  59.     
  60.     tmp = getline( "test" );
  61.     
  62.     would produce a list variable named `tmp' with 16 elements:
  63.     tmp.[1] would be the string "jcool" and tmp.[16] would be the
  64.     number 5.  The next call to getline() would read the second
  65.     line in the file, and create a new list containing those
  66.     elements.
  67.  
  68.     The above could also have been done with:
  69.  
  70.     tmp = getline( "|ps -aux | grep jcool" )
  71.  
  72.     Which would open a readable pipe to the "ps -aux | grep jcool"
  73.     command and grab a line at a time from the process.
  74.     
  75.     To read the entire contents of a file:
  76.  
  77.     if (length (ans = getline("stdin"))) 
  78.     { 
  79.       // do something with ans
  80.     else
  81.       // finish up
  82.         }
  83.  
  84.     Since getline returns an empty list when there is no input, we
  85.     can tell when to terminate the input loop by checking the
  86.     length of the returned list.
  87.  
  88. See Also: FILES, LIST
  89.